messageDigest

Type

function

Summary

Computes a cryptographic message digest.

Syntax

messageDigest(<message>, <digestType>)

Description

Compute a message digest of message using the cryptographic hash function digestType.

A cryptographic hash function is a mathematical algorithm that maps data of an arbitrary length to a fixed-length binary data string. It has the special property that it is designed to be a one-way function; if you are given the output of the cryptographic hash function (the "message digest"), it should be impossible to guess the input to the function (the "message").

Even a very small change to the message will make a very large change to the messageDigest. This makes it useful for whether data has changed.

The messageDigest function can be used:

• as a checksum to ensure that the message has not been corrupted or modified in storage or transmission
• as a "fingerprint" that summarizes the message
• as part of an authentication system
• to detect duplicate data

The messageDigest function supports the following standardised cryptographic hash functions. Numbers like "256", "384" etc. indicate the number of bits of binary data that the messageDigest function returns; for example, if you specify the "SHA3-256" digestType, then messageDigest will return 32 bytes of data.

Name	digestType	Notes
MD5	"MD5"	MD5 is cryptographically broken and unsuitable for further use. Do not use for security-critical purposes, unless required for backward compatibility with existing systems.
SHA-1	"SHA-1"	SHA-1 has been severely weakened and there are practical approaches for generating collisions. Do not use for security-critical purposes, unless required for backward compatibility with existing systems.
SHA-2	"SHA-224", "SHA-256", "SHA-384", "SHA-512"	SHA-2 has been found to have some minor weaknesses.
SHA-3	"SHA3-224", "SHA3-256", "SHA3-384", "SHA3-512"	SHA-3 has no known weaknesses

When generating a messageDigest for a string, it is a good idea to encode it to binary data using the textEncode function. Otherwise, the messageDigest could be different, depending on the platform on which your application is running.

In some cases you may wish to use a irreversible, keyed one-way transform of data, for example in a password storage scheme. You can use the messageDigest function to implement a keyed-hash message authentication code, as described in RFC 2014.

Parameters

Name	Type	Description
message	data	A binary data string.
digestType	enum	The cryptographic hash function to use.

Examples

-- Compute a message digest and store the result in "it"
get messageDigest("LiveCode", "SHA3-256")

-- Compute a simplified hash-based message authentication code (HMAC)
-- for a message using SHA3-256.  Consider using the full RFC 2104
-- HMAC algorithm.
put randomBytes(32) into tKey -- Save this key for later!
put textEncode("Try my LiveCode app", "UTF-8") into tMessage
get messageDigest(tKey & messageDigest(tKey & tMessage, \
            "SHA3-256"), "SHA3-256")

-- You can use a message digest to detect changes in data.
-- For example, you could store the checksum alongside or as
-- part of a file on disk.
put textEncode("My very large data", "UTF-8") into tOriginal
put messageDigest(tOriginal, "SHA3-256") into tChecksum
-- ... some time later ...
put textEncode("My very large data", "UTF-8") into tLoaded
if messageDigest(tLoaded, "SHA3-256") is not tChecksum then
   put "The data changed and may be corrupted!"
end if

Related

function: md5digest, sha1digest, textEncode

glossary: binary data, checksum, function, platform

Compatibility and Support

Introduced

LiveCode 9.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile